home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1996 July: Mac OS SDK / Dev.CD Jul 96 SDK / Dev.CD Jul 96 SDK1.toast / Development Kits (Disc 1) / OpenDoc / OpenDoc Development / Debugging Support / OpenDoc Source Code / Utilities / Interfaces / FocusLib.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-04-22  |  5.3 KB  |  199 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        FocusLib.h
  3.  
  4.     Contains:    Library routines for focusing (setting up for drawing into a facet)
  5.  
  6.     Owned by:    Jens Alfke
  7.  
  8.     Copyright:    © 1993 - 1995 by Apple Computer, Inc., all rights reserved.
  9.          
  10.          
  11.     THEORY OF OPERATION:
  12.     
  13.         FocusLib sets up the drawing environment for a QuickDraw-based part so that
  14.         it can start drawing into a facet. It provides both a one-time change of
  15.         focus (via the Focus call) and a way to set the focus but restore it later
  16.         when the current scope exits (via the CFocus object.)
  17.         
  18.         Focus() and FocusWindow() are slightly different for offscreen facets. If the
  19.         facet is in an offscreen canvas, Focus will set up to draw into that canvas;
  20.         this is what one usually wants to do. On the other hand, FocusWindow will
  21.         always focus onto an on-screen canvas, even for an off-screen facet. Use
  22.         FocusWindow for things like rubber-banding where your drawing needs to show
  23.         up immediately, even if the facet is offscreen.
  24.  
  25.         The CFocus object deserves an example:
  26.         
  27.         void DrawSomething( ODFacet *facet )
  28.         {
  29.             CFocus f(facet);        // Creates a CFocus object on the stack, which
  30.                                     // changes the focus but stores the old state
  31.             ....drawing code...
  32.         }
  33.         
  34.         Declaring the CFocus object calls its constructor, which sets the focus and
  35.         stores the old state in the CFocus object itself (on the stack.) When its
  36.         scope exists, the CFocus object's destructor is called, which restores the
  37.         old focus.
  38.         
  39.         CFocus inherits from Destructo (see Except.h) so it will now be destructed
  40.         properly if an exception is thrown while it's active. You no longer need to
  41.         catch the exception and manually destruct the CFocus.
  42. */
  43.  
  44.  
  45. #ifndef _FOCUSLIB_
  46. #define _FOCUSLIB_
  47.  
  48. #ifndef _EXCEPT_
  49. #include <Except.h>
  50. #endif
  51.  
  52. #ifndef __QUICKDRAW__
  53. #include <QuickDraw.h>
  54. #endif
  55.  
  56. #ifndef _ODTYPES_
  57. #include <ODTypes.h>
  58. #endif
  59.  
  60.  
  61. #ifdef __cplusplus
  62.     class ODCanvas;
  63.     class ODShape;
  64.     class ODFacet;
  65.     struct Environment;
  66. #else
  67.     #ifndef som_h
  68.     #include <som.h>
  69.     #endif
  70.     #ifndef SOM_ODCanvas_h
  71.     #include <Canvas.h>
  72.     #endif
  73.     #ifndef SOM_ODShape_h
  74.     #include <Shape.h>
  75.     #endif
  76.     #ifndef SOM_ODFacet_h
  77.     #include <Facet.h>
  78.     #endif
  79. #endif
  80.  
  81.  
  82. /*    FocusState stores the state data for QD focusing.
  83.     C users should allocate one on the stack and call BeginFocus and
  84.     EndFocus (q.v.) to do the focusing.
  85.     C++ users should ignore FocusState and simply allocate a CFocus object
  86.     (see below).
  87. */
  88.  
  89. struct FocusState
  90. {
  91.     GrafPtr        fPort;                        // Port to restore after unfocusing
  92.     Point        fOrigin;
  93.     RgnHandle    fClip;
  94.     ODBoolean    fPrintingPostScript;
  95.     GrafPtr        fFocusPort;                    // Port we're focusing to
  96.  
  97. #ifdef __cplusplus
  98.     ODBoolean    BeginFocus( Environment*, ODFacet*, ODBoolean toContent,
  99.                         ODBoolean toWindow, ODShape *clipTo );
  100.     void        EndFocus( );
  101. #endif
  102. };
  103. typedef struct FocusState FocusState;
  104.  
  105.  
  106. /*    CFocus is a class for C++ users. Just allocate one as a local variable:
  107.     the constructor will focus, and the destructor (called when it goes out
  108.     of scope or an exception is thrown) will unfocus.
  109.     CFocusWindow is just like CFocus, but focuses to the window instead of
  110.     the facet's canvas (if they're different.)
  111. */
  112.  
  113. #ifdef __cplusplus
  114. class CFocus :public Destructo {
  115.     public:
  116.     CFocus( Environment*, ODFacet* );
  117.     CFocus( Environment*, ODFacet*, ODShape *clipTo );
  118.     virtual ~CFocus();
  119.     
  120.     ODBoolean PrintingPostScript( )            {return f.fPrintingPostScript;}
  121.     
  122.     protected:
  123.     FocusState f;
  124. };
  125. #define CFocusContent CFocus
  126.  
  127. class CFocusFrame :public Destructo {
  128.     public:
  129.     CFocusFrame( Environment*, ODFacet* );
  130.     CFocusFrame( Environment*, ODFacet*, ODShape *clipTo );
  131.     virtual ~CFocusFrame();
  132.     
  133.     ODBoolean PrintingPostScript( )            {return f.fPrintingPostScript;}
  134.     
  135.     protected:
  136.     FocusState f;
  137. };
  138.  
  139. class CFocusWindow :public Destructo {
  140.     public:
  141.     CFocusWindow( Environment* ev, ODFacet* );
  142.     CFocusWindow( Environment*, ODFacet*, ODShape *clipTo );
  143.     virtual ~CFocusWindow();
  144.     
  145.     ODBoolean PrintingPostScript( )            {return f.fPrintingPostScript;}
  146.     
  147.     protected:
  148.     FocusState f;
  149. };
  150. #define CFocusWindowContent CFocusWindow
  151.  
  152. class CFocusWindowFrame :public Destructo {
  153.     public:
  154.     CFocusWindowFrame( Environment* ev, ODFacet* );
  155.     CFocusWindowFrame( Environment*, ODFacet*, ODShape *clipTo );
  156.     virtual ~CFocusWindowFrame();
  157.     
  158.     ODBoolean PrintingPostScript( )            {return f.fPrintingPostScript;}
  159.     
  160.     protected:
  161.     FocusState f;
  162. };
  163.  
  164. #endif
  165.  
  166.  
  167. #ifdef __cplusplus
  168. extern "C" {
  169. #endif
  170.  
  171. // For C only:
  172. void BeginFocus( Environment*, FocusState*, ODFacet*, ODBoolean toContent,
  173.                      ODBoolean toWindow, ODShape* clipTo );
  174. void EndFocus( FocusState* );
  175.  
  176.  
  177. // ODBeginPostScriptClip sets the PostScript clipping path to the given shape.
  178. // ODEndPostScriptClip resets PostScript clipping.
  179. // Neither has any effect except while printing to a PostScript printer.
  180. // If you are using FocusLib to do your clipping you don't need to call these.
  181. void ODBeginPostScriptClip( Environment* ev, ODShape* );
  182. void ODEndPostScriptClip(  );
  183.  
  184.  
  185. // GetCanvasGeometryMode returns the proper geometry mode to use for shapes
  186. // being used on a given canvas. This is usually kODLoseGeometry, indicating
  187. // that regions can be used for greater efficiency, or kODPreserveGeometry
  188. // when printing to a PostScript printer or via any GX print job.
  189. // This function should be used to get the geometry mode to be used for
  190. // shapes related to clipping.
  191.  
  192. ODGeometryMode GetCanvasGeometryMode( Environment *ev, ODCanvas *canvas );
  193.  
  194. #ifdef __cplusplus
  195. }
  196. #endif
  197.  
  198. #endif //_FOCUSLIB_
  199.